<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta content='width=device-width, initial-scale=1.0' name='viewport'>
    <meta content='' name='description'>
    <meta content='Nils Nordman' name='author'>
    <link href='/images/howl.png' rel='shortcut icon'>
    <title>Howl :: howl.signal</title>
    <link href="/stylesheets/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/syntax.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/howl.css" media="screen" rel="stylesheet" type="text/css" />
    <script src="https://code.jquery.com/jquery-1.12.3.min.js" type="text/javascript"></script>
    <script src="/javascripts/bootstrap.min.js" type="text/javascript"></script>
    
    <link href='//fonts.googleapis.com/css?family=Josefin+Slab' rel='stylesheet' type='text/css'>
    <link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:700' rel='stylesheet' type='text/css'>
  </head>
  <body class='doc doc_api doc_api_signal'>
    <div class='container'>
      <div class='masthead'>
        <ul class='nav nav-pills'>
          <li>
            <a href='/'>
              <span class='glyphicon glyphicon-home'></span>
              Home
            </a>
          </li>
          <li>
            <a href='/doc/'>
              <span class='glyphicon glyphicon-book'></span>
              Documentation
            </a>
          </li>
          <li>
            <a href='/blog/'>
              <span class='glyphicon glyphicon-bullhorn'></span>
              Blog
            </a>
          </li>
          <li>
            <a href='/contact.html'>
              <span class='glyphicon glyphicon-inbox'></span>
              Contact
            </a>
          </li>
        </ul>
      </div>
      <ol class="breadcrumb"><li><a href="/">Home</a></li><li><a href='../'>Howl 0.4 Documentation</a></li><li>Api</li><li>howl.signal</li></ol>
      <h1 id="howl.signal">howl.signal</h1>    <div class="toc">
      <div class="toc-title">
        <span>howl.signal</span>
      </div>
      <div class="toc-entries">
<div class="toc-group">
<a href="#overview" class="toc-group-header overview">Overview</a>
</div>
<div class="toc-group">
<a href="#properties" class="toc-group-header properties">Properties</a>
<li class=""><a href="#.abort">.abort</a></li>
<li class=""><a href="#.all">.all</a></li>
</div>
<div class="toc-group">
<a href="#functions" class="toc-group-header functions">Functions</a>
<li class=""><a href="#connect">connect </a></li>
<li class=""><a href="#disconnect">disconnect </a></li>
<li class=""><a href="#emit">emit </a></li>
<li class=""><a href="#register">register </a></li>
<li class=""><a href="#unregister">unregister </a></li>
</div>
</div>
</div>
&#x000A;&#x000A;<h2 id="overview">Overview</h2>&#x000A;&#x000A;<p>Signals provide a way of sending and receiving notifications about various&#x000A;events that happens within Howl. For example, there are signals emitted whenever&#x000A;text is added or deleted in a buffer, or a key is pressed in Howl, etc. By&#x000A;&ldquo;connecting&rdquo; a handler for signal, you can easily hook into the ordinary&#x000A;workings to add your own additional functionality. Signals are defined by their&#x000A;name, and each signal can provide additional information about the event as&#x000A;parameters. Each signal can have multiple handlers connected at a given time,&#x000A;which will all be invoked, provided a handler does not explicitly halt the&#x000A;processing (see <a href="#emit">emit</a> for more information).</p>&#x000A;&#x000A;<p>To view the list of currently registered signals within Howl as well as&#x000A;information about the parameters you can use the <code>describe-signal</code> command.</p>&#x000A;&#x000A;<p><em>See also</em>:</p>&#x000A;&#x000A;<ul>&#x000A;<li>The <a href="../spec/signal_spec.html">spec</a> for signal</li>&#x000A;</ul>&#x000A;&#x000A;<h2 id="properties">Properties</h2>&#x000A;&#x000A;<h3 id=".abort">.abort</h3>&#x000A;&#x000A;<p>A sentinel value used for causing an early exit during signal dispatch (see&#x000A;<a href="#emit">emit</a> for more information).</p>&#x000A;&#x000A;<h3 id=".all">.all</h3>&#x000A;&#x000A;<p>This is a table of all currently defined signals within Howl, keyed by their&#x000A;name. The value associated with each key is the  signal information as passed to&#x000A;<a href="#register">register</a>.</p>&#x000A;&#x000A;<h2 id="functions">Functions</h2>&#x000A;&#x000A;<h3 id="connect">connect <span class="arg-list">(name, handler [, index])</span></h3>&#x000A;&#x000A;<p>Connects <code>handler</code> to the signal specified by <code>name</code>. The optional <code>index</code>&#x000A;argument specifies where in the handler list the handler should be placed. All&#x000A;handlers for a specific signal are stored in a list, and the index specifies the&#x000A;order in which they are invoked whenever a signal is emitted, where the handler&#x000A;with index 1 is invoked first, followed by handlers with greater indices.</p>&#x000A;&#x000A;<p>An error is raised when trying to connect a handler for a signal that has not&#x000A;been registered.</p>&#x000A;&#x000A;<h3 id="disconnect">disconnect <span class="arg-list">(name, handler)</span></h3>&#x000A;&#x000A;<p>Disconnects <code>handler</code> from the signal specified by <code>name</code>.</p>&#x000A;&#x000A;<h3 id="emit">emit <span class="arg-list">(name, parameters)</span></h3>&#x000A;&#x000A;<p>Emits the signal specified by <code>name</code>, along with any optional parameters&#x000A;contained in <code>parameters</code>. <code>parameters</code>, if specified, should be a table with&#x000A;keys matching those of the parameters specified for <a href="#register">register</a>. An&#x000A;error is raised when trying to emit a signal that has not been registered.</p>&#x000A;&#x000A;<p>When a signal is emitted each connected handler is invoked in turn, with&#x000A;<code>parameters</code> as the sole argument. Should any handler return <code>signal.abort</code>, the&#x000A;processing is halted and <code>emit</code> in turn returns <code>signal.abort</code>. Otherwise,&#x000A;<code>false</code> is returned. Any error triggered in a signal handler is logged, and&#x000A;processing continues.</p>&#x000A;&#x000A;<h3 id="register">register <span class="arg-list">(name, options)</span></h3>&#x000A;&#x000A;<p>Registers the signal specified in <code>name</code>, with the options specified in&#x000A;<code>options</code>. <code>options</code> can contain the following fields:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>description</code>: A textual description of what the signal is for (<em>required</em>)</li>&#x000A;</ul>&#x000A;&#x000A;<p><em>Example of how to register a signal</em>:</p>&#x000A;<pre class="highlight moonscript"><span class="n">signal</span><span class="p">.</span><span class="n">register</span><span class="w"> </span><span class="s1">'mode-registered'</span><span class="p">,</span><span class="w">&#x000A;  </span><span class="ss">description:</span><span class="w"> </span><span class="s1">'Signaled right after a mode was registered'</span><span class="p">,</span><span class="w">&#x000A;  </span><span class="ss">parameters:</span><span class="w">&#x000A;    </span><span class="ss">name:</span><span class="w"> </span><span class="s1">'The name of the mode'</span><span class="w">&#x000A;</span></pre>&#x000A;<h3 id="unregister">unregister <span class="arg-list">(name)</span></h3>&#x000A;&#x000A;<p>Unregisters the signal specified by <code>name</code>.</p>
      <div class='footer text-muted'>
        <a href='/'>
          <img width="50" height="50" class="footer-logo" src="/images/howl.png" />
        </a>
        <div class='footer-follow'>
          <p>
            <a class='twitter-follow-button' data-lang='en' data-show-count='false' href='https://twitter.com/howleditor' rel='me'>
              Follow @howleditor
            </a>
          </p>
          <p>
            <a class='twitter-share-button' data-count='none' data-hashtags='howleditor' data-lang='en' data-text='The Howl Editor, a general purpose, light-weight customizable editor.' data-url='http://howl.io' href='https://twitter.com/share'>
              Tweet
            </a>
          </p>
        </div>
        <div class='footer-blurb'>
          <div>The Howl editor.</div>
          <div>
            Copyright 2012-2016
            <a class='alert-link' href='https://github.com/howl-editor/howl/contributors'>
              The Howl Developers.
            </a>
          </div>
        </div>
      </div>
    </div>
    <script>
      <!-- / GA -->
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
      ga('create', 'UA-45283282-1', 'howl.io');
      ga('send', 'pageview');
      <!-- / Twitter -->
      !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];
      if(!d.getElementById(id)){js=d.createElement(s);js.id=id;
      js.src="//platform.twitter.com/widgets.js";
      fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
    </script>
  </body>
</html>
